feat(openai-official): add OpenAI Responses API module - #3078

🟡 Changes recommended

There are correctness/usability issues in provider configuration and connection-field validation (env base URL resolution and blank-value normalization) that should be fixed before merging.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

        String effectiveBaseUrl = effectiveOptions.getBaseUrl();
        if (effectiveBaseUrl != null && !Objects.equals(effectiveBaseUrl, baseUrl)) {
            throw new OpenAIOfficialModelException(

    /** GPT-5.4-mini with Multi-Agent Formatter. */

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

已审。重点检查了新增 openai-official Responses 模块的请求映射、非流式解析、流式事件拼装、usage/metadata/finishReason、工具调用回放、错误转换、provider SPI、BOM/distribution 接入和相关测试覆盖。\n\n本地验证：mvn -pl agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-openai-official -am test -DskipITs 通过，274 tests, 0 failures/errors, 2 skipped。\n\n未发现需要阻塞合并的问题。

Thanks for the large integration. I found one release-blocking issue in the all-in-one distribution: the new module is present in the shaded jar, but its ModelProvider service entry is not merged, so ModelRegistry cannot discover openai-official models when users depend on the agentscope artifact.

Verification run locally on PR head 0bcf01970ce985d0f973c81fefc9b30e241ed9fe:

• mvn -pl agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-openai-official -am test passed: 274 tests, 0 failures, 2 skipped
• mvn -pl agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-e2e-tests -am test-compile -DskipTests passed
• bash .github/scripts/check-shade-and-bom-sync.sh passed
• mvn -pl agentscope-distribution/agentscope-all -am package -DskipTests passed, but emitted the overlapping META-INF/services/io.agentscope.core.model.spi.ModelProvider warning; inspecting the resulting jar confirmed the new provider is missing from the service descriptor.

Requesting changes based on two concrete correctness issues.

[HIGH] Multi-agent formatter drops encrypted reasoning replay

File: agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-openai-official/src/main/java/io/agentscope/extensions/model/openaiofficial/ResponsesMultiAgentFormatter.java (line 175)

When OpenAIResponsesChatModel is configured with ResponsesMultiAgentFormatter, all history mapping goes through formatter::formatHistory. For an ordinary assistant turn that contains ThinkingBlock plus openai.reasoning.encrypted_content metadata, determineGroupType classifies it as AGENT_CONVERSATION; mergeAgentConversation then rewrites it into a user <history> message and processMessage only appends the visible thinking/text content. It never calls ResponsesRequestMapper.mapAssistantMessage, so no ResponseReasoningItem with encrypted_content is sent on the next request.

This breaks the PR's documented reasoning replay behavior exactly for the sample configuration that combines reasoning with ResponsesMultiAgentFormatter. I verified with a minimal probe: the formatted history for user -> assistant(thinking + encrypted metadata) -> user produced items=1 reasoning=0 easy=1.

Why tests miss it: CrossTurnTest verifies encrypted replay only with the default mapper, and ResponsesMultiAgentFormatterTest covers thinking text but never asserts that encrypted reasoning metadata is preserved.

Suggested fix: make formatter preserve assistant messages with openai.reasoning.encrypted_content as Responses reasoning replay items, or classify them into a passthrough path that delegates to ResponsesRequestMapper.mapAssistantMessage. Add a regression test that builds OpenAIResponsesChatModel with new ResponsesMultiAgentFormatter() and asserts the second-turn ResponseCreateParams.input contains a reasoning item with the encrypted content.

[MEDIUM] Per-schema strict mode is ignored for JSON schema response formats

File: agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-openai-official/src/main/java/io/agentscope/extensions/model/openaiofficial/ResponsesRequestMapper.java (line 185)

JsonSchema already exposes getStrict(), but the Responses mapper only sets schemaBuilder.strict(...) from the builder-level strictJsonSchema. A caller using ResponseFormat.jsonSchema(JsonSchema.builder().strict(true).build()) silently gets a request without strict: true unless they also set the model builder flag.

Why tests miss it: the tests only cover builder-level strictJsonSchema; there is no test where JsonSchema.strict(true) is set on the response format itself.

Suggested fix: resolve strict as schema.getStrict() != null ? schema.getStrict() : strictJsonSchema, then set it when non-null. Add a test that schema-level strict is propagated and that builder-level remains a fallback.

Validation run:

• mvn -pl agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-openai-official -am test -DskipITs passed: 274 tests, 0 failures, 2 skipped.
• Java LSP diagnostics were unavailable in this environment; the exposed diagnostic tool runs npx tsc, so Maven compile/tests were used as the Java diagnostic substitute.
• ast-grep was not installed; I used rg for hardcoded secret/debug/empty-catch/problem-pattern scanning.

已复核 PR head 0bcf019。重点检查了 openai-official Responses 模块的请求映射、ReasoningContext metadata 持久化与后续 encrypted reasoning replay、流式 terminal metadata/usage 聚合、工具调用回放、provider SPI、BOM/distribution 接入和 retry 配置组合；未发现需要阻塞合并的问题。\n\nGitHub checks 当前通过：Java build ubuntu/windows、Check License、Check Module Sync、Codecov、CLA、Mintlify validate。\n\n结论：APPROVE。

Requesting changes after re-checking PR head 0bcf019. I found release-blocking correctness issues that should be fixed before merge.

[HIGH] Multi-agent formatter drops encrypted reasoning replay

OpenAIResponsesChatModel sends all history through formatter::formatHistory when a ResponsesMultiAgentFormatter is configured (OpenAIResponsesChatModel.java:112-122). In that path, ordinary assistant messages are classified as AGENT_CONVERSATION unless they contain tool blocks (ResponsesMultiAgentFormatter.java:172-181), and mergeAgentConversation rewrites them into a user <history> message (ResponsesMultiAgentFormatter.java:209-237). processMessage then serializes ThinkingBlock as visible text (ResponsesMultiAgentFormatter.java:305-312) and never delegates to ResponsesRequestMapper.mapAssistantMessage, which is the only code path that emits the Responses reasoning replay item from openai.reasoning.encrypted_content metadata (ResponsesRequestMapper.java:433-445, ResponsesRequestMapper.java:477-493).

This breaks stateless reasoning replay exactly for the documented reasoning + multi-agent formatter usage. Please preserve assistant messages with encrypted reasoning metadata as Responses reasoning input items, or route them through a passthrough/delegation path, and add a regression test that configures OpenAIResponsesChatModel with new ResponsesMultiAgentFormatter() and asserts second-turn input contains the encrypted ResponseReasoningItem.

[MEDIUM] Schema-level strict mode is ignored for JSON schema structured output

JsonSchema exposes strict (JsonSchema.java:91-96), but ResponsesRequestMapper only writes schemaBuilder.strict(...) from the model-level strictJsonSchema flag (ResponsesRequestMapper.java:178-187). A caller setting ResponseFormat.json_schema with JsonSchema.strict(true) silently gets a request without strict: true unless they also configure the model builder flag.

Please resolve strict as schema-level first, then builder-level fallback, e.g. schema.getStrict() != null ? schema.getStrict() : strictJsonSchema, and add tests for schema-level override plus builder-level fallback.

[HIGH] all-in-one shaded artifact can lose ModelProvider service registration

The new module is added to agentscope-all (agentscope-all/pom.xml:111-116) and has its own SPI file (agentscope-extensions-model-openai-official/src/main/resources/META-INF/services/io.agentscope.core.model.spi.ModelProvider:1). But the shade config only includes artifacts and has no ServicesResourceTransformer or equivalent service merge (agentscope-all/pom.xml:449-466). There are multiple model-provider service descriptors across extension modules, so the shaded jar can keep only one descriptor and drop OpenAIOfficialModelProvider, making ModelRegistry discovery fail for users depending on the all-in-one agentscope artifact.

Please add a service resource transformer to the shade plugin and a packaging regression check that the shaded jar's META-INF/services/io.agentscope.core.model.spi.ModelProvider contains io.agentscope.extensions.model.openaiofficial.OpenAIOfficialModelProvider.

CI is green, but these are behavioral/package correctness issues not covered by the current checks.

One additional blocking issue affects the default formatter path as well.

[HIGH] The production ReActAgent path discards encrypted reasoning metadata before the next turn

ResponsesResponseParser stores openai.reasoning.encrypted_content only in the terminal ChatResponse.metadata (lines 105-106), and the streaming path does the same in ResponsesStreamingAssembler (lines 261-263). However, the production consumer, ReasoningContext.processChunk, never reads chunk.getMetadata(); buildFinalMessage() creates a fresh metadata map containing only MessageMetadataKeys.CHAT_USAGE. The resulting assistant Msg therefore cannot contain the key that ResponsesRequestMapper.mapAssistantMessage looks up at lines 434-444.

As a result, encrypted reasoning replay is unreachable through a normal ReActAgent call even without ResponsesMultiAgentFormatter. This is particularly important for stateless reasoning/tool-call loops, where the reasoning item from the prior response must be sent back with the function-call output. The current cross-turn tests miss this because they manually construct an AssistantMessage with openai.reasoning.encrypted_content already present instead of exercising ChatResponse -> ReasoningContext -> Msg -> next request.

Please preserve the terminal response metadata in the final assistant message (or place the replay data on a content block and ensure its accumulator preserves it), and add a ReActAgent-level two-iteration regression test that captures the second ResponseCreateParams and asserts it contains the prior encrypted reasoning item.